home *** CD-ROM | disk | FTP | other *** search
/ Visual Basic Source Code / Visual Basic Source Code.iso / vbsource / wrcmdd / rcmddll.doc < prev    next >
Encoding:
Text File  |  1995-02-28  |  13.8 KB  |  422 lines
  1.   Winsock RCMD.DLL                                   Version 1.5
  2.   Copyright 1994 Denicomp Systems
  3.   All rights reserved
  4.   
  5.   DESCRIPTION
  6.   -----------
  7.   
  8.   Winsock RCMD.DLL is a Microsoft Windows 3.1 Dynamic Link Library that
  9.   provides a Windows Sockets compatible function that allows you to execute
  10.   commands on a remote host and retreive the output of those commands for
  11.   processing by your program.
  12.  
  13.   Winsock RCMD.DLL is similar to the "rcmd" library function found on many
  14.   Unix systems.  The DLL includes the main WinsockRCmd function, plus a
  15.   functions receive data over the connection from the remote host executing
  16.   the command.
  17.   
  18.   The remote host must be a system running the rshd or rexecd daemon process,
  19.   such as a Unix system or a PC running Denicomp Systems' Winsock RSHD.
  20.  
  21.   Winsock RCMD.DLL is designed to execute non-interactive remote commands.
  22.   If you need to execute an interactive command on the remote host, use a
  23.   utility like Telnet.
  24.   
  25.  
  26.   REQUIREMENTS
  27.   ------------
  28.  
  29.   Winsock RCMD.DLL requires a PC running Windows 3.1 or higher, a Windows
  30.   Sockets compatible TCP/IP stack, and any programming language that supports
  31.   calls to DLL functions, such as C or Visual Basic.
  32.  
  33.  
  34.   =============================================================================
  35.  
  36.   FUNCTION: WinsockRCmd
  37.  
  38.   Syntax:
  39.   -------
  40.  
  41.   C:
  42.   
  43.   int FAR PASCAL WinsockRCmd (Host, Port, LocalUser, RemoteUser,
  44.                          Command, ErrorMsg, ErrorMsgLen)
  45.   
  46.        LPSTR Host;
  47.        int Port;
  48.        LPSTR LocalUser;
  49.        LPSTR RemoteUser;
  50.        LPSTR Command;
  51.        LPSTR ErrorMsg;
  52.        int ErrorMsgLen;
  53.   
  54.  
  55.   Visual Basic:
  56.  
  57.   Declare Function WinsockRCmd Lib "RCMD.DLL"
  58.               (ByVal RHost As String,
  59.                ByVal RPort As Integer,
  60.                ByVal LocalUser As String,
  61.                ByVal RemoteUser As String,
  62.                ByVal Cmd As String,
  63.                ByVal ErrorMsg As String,
  64.                ByVal ErrLen As Integer) As Integer
  65.  
  66.  
  67.   Usage:
  68.   ------
  69.   
  70.   The WinsockRCmd function initiates a connection to the remote host
  71.   and executes the specified command if access is permitted.  You can
  72.   then use the RCmdRead function to receive the standard output and
  73.   standard error output of the command.
  74.   
  75.   Parameters:
  76.   -----------
  77.  
  78.   Host:        Specifies the name of a remote host that is listed in the 
  79.                "hosts" file.  You will receive an error if the host name
  80.                is not found.
  81.   
  82.   Port:        Specifies the port to use for the connection.  Normally, this
  83.                is the well-known port number of 514 for the rshd daemon.  You
  84.                may also use port 512 for the rexecd daemon.
  85.  
  86.                The rshd and rexecd daemons are very similar.  The only
  87.                difference is that the rexecd daemon requires you to specify
  88.                the user's correct password in the RemoteUser parameter.
  89.   
  90.   LocalUser:   The user name of the user on the local host (the PC).  This can
  91.                be NULL or an empty string if you want Winsock RCMD.DLL to
  92.                determine the name.  The method it uses is described later.
  93.  
  94.                This name is sent as the local user to the rshd daemon on the
  95.                remote host.  In general, it should be the same as the
  96.                RemoteUser parameter.
  97.  
  98.   RemoteUser:  When using rshd (port 514), this is the user name to be used at
  99.                the remote host.  This must be a valid user name at the remote
  100.                host.  It can be NULL or an empty string if you want Winsock
  101.                RCMD.DLL to detemrine the name.  The method is uses it
  102.                described later.
  103.  
  104.                When using rexecd (port 512), you must specify the password
  105.                of the user specified in the LocalUser parameter here.  If
  106.                the password is invalid, an error will be returned from
  107.                the remote host.
  108.  
  109.                Note that your program is responsible for supplying the
  110.                password.  For example, you could ask the user to enter it
  111.                or it could be stored in a configuration file.  Winsock RCMD.DLL
  112.                will not request it.
  113.               
  114.   
  115.   Command:     The command to be executed at the remote host.
  116.   
  117.   ErrorMsg:    A pointer to an area that can be used to store an error
  118.                message from WinsockRCmd.  If an error occurs while connecting
  119.                to the remote host, WinsockRCmd will return a negative result
  120.                and will store an error message here.  You can then optionally
  121.                use the error message as diagnostic output in your program.
  122.  
  123.   ErrorMsgLen: The maximum length of the error message returned.  This is
  124.                the number of characters available in ErrorMsg.
  125.   
  126.  
  127.   Return Value:
  128.   -------------
  129.  
  130.   If WinsockRCmd sucessfully connects to the remote host and begins executing
  131.   the specified command, it will return an integer "handle" that must be used
  132.   by the RCmdRead, RCmdHandle, and RCmdClose functions.  This handle will always
  133.   be greater than or equal to zero.
  134.   
  135.   If WinsockRCmd is not successful, it will return a negative number.  If the
  136.   number is -1, an error internal to WinsockRCmd occurred and a message
  137.   describing the error will be stored in ErrorMsg.  If the number is not -1,
  138.   it is a Windows Sockets error code (but negative).  ErrorMsg will also
  139.   contain a message attempting to describe the error.
  140.   
  141.   Notes:
  142.   ------
  143.  
  144.   The error message returned in ErrorMsg may contain newline characters
  145.   (ASCII 10).  The message is suitable for display using the standard
  146.   Windows MessageBox function or the Visual Basic MsgBox command/function.
  147.  
  148.   Execution of interactive commands (commands requiring keyboard input) is
  149.   not supported.
  150.  
  151.   Unlike the Unix "rcmd" function, WinsockRCmd does not have the ability
  152.   to separate the standard output and the standard error output of the
  153.   remote command.  Output to the standard output and standard error will
  154.   be intermixed.
  155.   
  156.  
  157.   Windows Sockets "Shutdown" or "Connection Refused" Errors
  158.   ---------------------------------------------------------
  159.  
  160.   With a very few TCP/IP packages, you may experience Windows Sockets
  161.   "Shutdown" errors (-10058) or "Connection Refused" errors (-10061)
  162.   from the WinsockRCmd function call in definite patterns.  For example,
  163.   you may receive the error every other call or every third call.
  164.   If you do, you should make provisions in your program to retry the
  165.   call to WinsockRCmd on the error (with a limit on the number of retries
  166.   to avoid an endless loop on a true problem).  For example:
  167.  
  168.   
  169.        #define MAX_RETRIES 10
  170.  
  171.        int retries = 0;
  172.        do {
  173.             result = WinsockRCmd(...);
  174.             ++retries;
  175.        } while ((result == -10058 || result == -10061) &&
  176.                 retries < MAX_RETRIES);
  177.  
  178.  
  179.   Using the rexecd Daemon
  180.   -----------------------
  181.  
  182.   If you wish to use the rexecd daemon instead of rshd, specify a port number
  183.   of 512 instead of 514 in the WinsockRCmd function call.
  184.  
  185.   The rexecd daemon is similar to the rshd server, except that it requires
  186.   a password to be supplied.  You must make provisions in your software to
  187.   allow the user to enter the password at the appropriate time or retrieve
  188.   it from some storage area (i.e. an initialization file).  Winsock RCMD.DLL
  189.   does NOT ask for the password.
  190.  
  191.   When using rexecd, in addition to using port 512 instead of 514, you must
  192.   pass the password in the RemoteUser parameter in the WinsockRCmd function
  193.   call (the fourth parameter).  All other parameters and the remaining
  194.   functions described in this manual function in the same manner.
  195.        
  196.  
  197.   =============================================================================
  198.  
  199.   Syntax:
  200.   -------
  201.  
  202.   C:
  203.   
  204.   int FAR PASCAL RCmdRead (Handle, DataIn, DataLen)
  205.   
  206.        int Handle;
  207.        LPSTR DataIn;
  208.        int DataLen;
  209.  
  210.   Visual Basic:
  211.  
  212.   Declare Function RCmdRead Lib "RCMD.DLL"
  213.               (ByVal hRCmd As Integer,
  214.                ByVal RData As String,
  215.                ByVal RCount As Integer) As Integer
  216.  
  217.  
  218.   Usage:
  219.   ------
  220.   
  221.   The RCmdRead function reads the output of the command executed with
  222.   WinsockRCmd.  This allows you to capture the standard output and
  223.   standard error output of the command you executed.
  224.  
  225.   Parameters:
  226.   -----------
  227.  
  228.   Handle:     This is the integer "handle" returned from the WinsockRCmd
  229.               function.
  230.  
  231.   DataIn:     A pointer to an area of memory to hold the data received.
  232.  
  233.   DataLen:    The maximum number of bytes to receive.
  234.  
  235.  
  236.   Return Value:
  237.   -------------
  238.  
  239.   If RCmdRead is sucessful, it returns the number of bytes read.  It will be
  240.   a number greater than zero.
  241.  
  242.   If RCmdRead returns zero, there is no more data to read.  The command has
  243.   ended and you should call RCmdClose to terminate the connection.
  244.  
  245.   If RCmdRead returns a negative number, an error has occurred.  The number
  246.   will be the Windows Sockets error number (but negative).  You should call
  247.   RCmdClose even if an error occurs to free all resources used by the
  248.   connection.
  249.  
  250.  
  251.   =============================================================================
  252.  
  253.   Syntax:
  254.   -------
  255.  
  256.   C:
  257.   
  258.   int FAR PASCAL RCmdClose (Handle)
  259.   
  260.        int Handle;
  261.  
  262.   Visual Basic:
  263.  
  264.   Declare Function RCmdClose Lib "RCMD.DLL" (ByVal hRCmd As Integer) As Integer
  265.  
  266.  
  267.   Usage:
  268.   ------
  269.   
  270.   The RCmdClose function closes the connection to the remote host and
  271.   frees all resources used by the connection.  You should call RCmdClose
  272.   for each successful use of the WinsockRCmd function.
  273.  
  274.  
  275.   Parameters:
  276.   -----------
  277.  
  278.   Handle:     This is the integer "handle" returned from the WinsockRCmd
  279.               function.
  280.  
  281.  
  282.   Return Value:
  283.   ------------
  284.  
  285.   If RCmdClose is sucessful, it returns zero.  If it is unsuccessful, it
  286.   returns a negative number that is the Windows Sockets error number (but
  287.   negative).
  288.  
  289.  
  290.   =============================================================================
  291.  
  292.   Syntax:
  293.   -------
  294.  
  295.   C:
  296.   
  297.   int FAR PASCAL RCmdHandle (Handle)
  298.   
  299.        int Handle;
  300.  
  301.   Visual Basic:
  302.  
  303.   Declare Function RCmdHandle Lib "RCMD.DLL" (ByVal hRCmd As Integer) As Integer
  304.  
  305.  
  306.   Usage:
  307.   ------
  308.   
  309.   The RCmdHandle function returns the Windows Sockets handle for the
  310.   connection, which can be used to call any Windows Socket function.
  311.  
  312.  
  313.   Parameters:
  314.   -----------
  315.  
  316.   Handle:     This is the integer "handle" returned from the WinsockRCmd
  317.               function.
  318.  
  319.  
  320.   Return Value:
  321.   -------------
  322.  
  323.   RCmdHandle returns a Windows Sockets handle.  If you call RCmdHandle on
  324.   a WinsockRCmd connection that is not opened, the return value is undefined.
  325.  
  326.  
  327.  ============================================================================
  328.  
  329.   DETERMINING THE USER NAME
  330.   -------------------------
  331.  
  332.   If you use a NULL value or empty string for the LocalUser or RemoteUser
  333.   parameters of the WinsockRCmd function, the user name is determined by
  334.   first looking in the file WIN.INI in the Windows directory.  If this file
  335.   contains a section named "[RCMD]" and contains an entry named "User" in that
  336.   section, the name specified there will be used as the user name.  For
  337.   example, WIN.INI would contain:
  338.  
  339.      [RCMD]
  340.      User=joe
  341.  
  342.   If this appeared in WIN.INI, the user name would be "joe" and WinsockRCmd
  343.   would use this name.
  344.  
  345.   If this section does not appear in WIN.INI, WinsockRCmd uses the Computer
  346.   Name specified in the Windows for Workgroups Network Setup (found on the
  347.   Control Panel).  This name is converted to lowercase characters and
  348.   WinsockRCmd uses this name.  Therefore, if no user name is specified in
  349.   WIN.INI, the Computer Name of the PC must be set up as a valid user on the
  350.   remote host, in addition to being included in the remote host's
  351.   /etc/hosts.equiv file.
  352.  
  353.   (If you are not using Windows for Workgroups and your network does not
  354.   provide the services that Windows for Workgroups provides, you must use
  355.   WIN.INI to specify the user name.)
  356.  
  357.  
  358.   SECURITY
  359.   --------
  360.   
  361.   The remote host allows access only if at least one of the following
  362.   conditions is satisfied:
  363.   
  364.   * The name of the local host is listed as an equivalent host in the
  365.     /etc/hosts.equiv file on the remote host.
  366.  
  367.     The method of specifying the local host name is determined by the
  368.     particular TCP/IP stack you are using.
  369.   
  370.   * If the local host is not in the /etc/hosts.equiv file, the user's home
  371.     directory on the remote host must contain a .rhosts file that lists the
  372.     local host and user name.
  373.   
  374.   * The user's login on the remote host does not require a password.
  375.  
  376.   The .rhosts file in the user's home directory must be owned by either
  377.   the user specified or root, and only the owner should have read and write
  378.   access.
  379.   
  380.   EXAMPLE
  381.   -------
  382.  
  383.   For a complete example of the use of WinsockRCmd in C, see the CRSH
  384.   program provided in the distribution.
  385.  
  386.   For a example of the use of WinsockRCmd in Visual Basic, see the VRSH
  387.   program provided in the distribution.  This is actually the source code
  388.   of the Visual RSH program provided with the Winsock RCP and RSH package.
  389.  
  390.  
  391.   // Assumes that the host is in "rhost", the user is in "ruser", and the
  392.   // command is in "cmd".
  393.  
  394.      int hRCmd;
  395.      char c;
  396.  
  397.      hRCmd = WinsockRCmd(rhost,514,ruser,ruser,cmd,errmsg,sizeof(errmsg));
  398.  
  399.      if (hRCmd < 0)
  400.        MessageBox(NULL,errmsg,"Remote Shell",MB_OK);
  401.      else
  402.      {
  403.     while(RCmdRead(hRCmd,&c,1) > 0)
  404.           DisplayChar(c);
  405.      }
  406.  
  407.      RCmdClose(hRCmd);
  408.  
  409.  
  410. SUPPORT
  411. -------
  412.  
  413. Support is available via U.S. Mail and Compuserve/Internet:
  414.  
  415. Denicomp Systems
  416. P.O. Box 731
  417. Exton, PA  19341
  418.  
  419. Compuserve:  71612,2333
  420. Internet:    71612.2333@compuserve.com
  421.  
  422.